@{" 2.5. Writing Scripts " link "SWrite"} Writing IconInstaller scripts
REFERENCE
" link "Ref"} Detailed description
Window
" link "Win"} The user interface window
Menus
" link "Menu"} About the menus
ToolTypes
" link "TTypes"} The default settings
Script
Commands
" link "SCom"} Writing your own scripts
MISCELLANEOUS
" link "Misc"} Legal issues and tidbits
Copyright
" link "Copy"} Distribution
Disclaimer
" link "Disc"} Read this at your own risk
History
" link "Hist"} About different versions
Future
" link "Futu"} Is this not ready yet?
@{" 4.5. NewIcon Info " link "NIInfo"} To those unfamiliar with NewIcons
Author
" link "Author"} How to contact me
@endnode
@node "Intro" "INTRODUCTION"
@toc "Main"
1. INTRODUCTION
IconInstaller is a tool to aid in icon management. The @{"basic operation" link "BMode"} of
IconInstaller is to copy the imagery from one icon to another. Both standard
icons and @{"NewIcons" link "NIInfo"} are supported, including conversion from standard icons
to NewIcons, and vice versa. IconInstaller can also be used to copy other
attributes (such as tooltypes, position, default tool etc.) in addition to,
or instead of, the imagery.
IconInstaller has a mouse-driven graphical user interface, where icons can
be selected with simple dragging and dropping, or alternatively using
standard ASL file requesters. Unique to IconInstaller is a @{"script mode" link "SMode"},
where icons are selected for installation according to a script.
IconInstaller can also be used to easily @{"install whole drawers" link "DMode"} of icons
with a single command.
IconInstaller requires at least AmigaDOS release 2.04. For more info, there
is a detailed list of @{"requirements" link "Reqs"}.
For legal information, read the sections about @{"copyright" link "Copy"} and @{"disclaimer" link "Disc"}.
@endnode
@node "Reqs" "REQUIREMENTS"
@toc "Intro"
1.1. REQUIREMENTS
IconInstaller requires at least AmigaDOS version 2.04. Specifically, the
following libraries are needed:
asl.library
dos.library
exec.library
gadtools.library
graphics.library
icon.library
intuition.library
layers.library
workbench.library
Additionally, newicon.library is is used for NewIcon support. However,
newicon.library is not required to run IconInstaller.
IconInstaller takes up about 50 KBytes of disk space. At least about 100
KBytes of free RAM is required to run IconInstaller. If the subdirectory
mode is used with many nested levels of directories, more memory is consumed.
@endnode
@node "Inst" "INSTALLATION"
@toc "Intro"
1.2. INSTALLATION
There is no special installation procedure for IconInstaller. Simply drag
the program wherever you want it. For example, The 'Tools' drawer on your
Workbench disk is a good place.
@endnode
@node "Usage" "USAGE"
@toc "Main"
2. USAGE
IconInstaller is a very versatile tool, and can be used in many different
ways. There is a normal mode for installing icons one by one, a directory
mode for installing whole drawers of icons, and a script mode for selecting
icons for installation according to a script.
In its basic configuration, IconInstaller will copy the image from one icon
to another, but also other icon attributes, such as default tool, icon type,
position, etc., can be selected for installation. @{"NewIcon" link "NIInfo"} users can
also change the configuration to copy NewIcon images, and convert between
standard icons and NewIcons.
Basic
Usage
" link "BMode"} Installing and deleting icons manually
Directory
" link "DMode"} Installing to drawers
Script
" link "SMode"} Using a script to install icons
Configuration
" link "Config"} Changing the settings
Writing
Scripts
" link "SWrite"} Making your own scripts
@endnode
@node "BMode" "USAGE"
@toc "Usage"
2.1. BASIC USAGE
Start IconInstaller with a double click on its icon.
If you are using the @{"NewIcons" link "NIInfo"} system, a requester may appear asking you to
select from some image installation options.
IconInstaller will start as 'empty', with no icons selected. To install the
image from one icon to another, you'll need to open a source icon and a
destination icon. The easiest way to open an icon is to drag and drop it
into the IconInstaller window. Source icons can be dropped in the box
labeled @{"New Image" link "Win SBox"}, destination icons in the box labeled @{"Original Image" link "Win DBox"}.
You can also open icons using a file requester. Select @{"Open Source Icon..." link "PMenu SOpen"}
and @{"Open Destination Icon..." link "PMenu DOpen"}, respectively, from the 'Project' menu.
Finally, the destination icon can also be opened by typing its name into the
gadget labeled @{"Destination Icon" link "Win NGad"}.
When both source and destination icons are opened, you can click on the
@{"Install" link "Win IGad"} gadget to replace the original image of the destination icon with
the new one from the source. If you prefer using menus, you can also select
@{"Install Icon" link "PMenu IInst"} from the 'Project' menu.
IconInstaller can also be used to delete icons from files, leaving the file
associated with the icon intact. To delete an icon, open it as the
destination icon as described above. Then, select @{"Delete icon..." link "PMenu IDel"} from the
'Project' menu. IconInstaller will display a requester asking you to confirm
this action.
IconInstaller is also able to install multiple icons in one go, either a
whole @{"directory" link "DMode"} at once, or according to a @{"script" link "SMode"}.
Furthermore, you can @{"configure" link "Config"} the installation by selecting other icon
attributes to install from one icon to another, in addition to (or instead
of) the imagery, as well as change some other options.
@endnode
@node "DMode" "USAGE"
@toc "Usage"
2.2. DIRECTORY MODE
Please read first the section describing @{"basic
usage" link "BMode"} of IconInstaller,
where opening source and destination icons is explaned, before proceeding
with this section.
To start directory installation, open both source and destination icons.
Then, click on the @{"Dir" link "Win DGad"} gadget. A requester will appear, asking for the
directory (drawer) where the installation should take place. By default, this
is the directory where the destination icon is located.
IconInstaller will read the icons in the directory, one by one, and open
each icon in its turn as the destination icon. For each icon, you can select
to install the image from the source icon, or skip the icon and move on to
the next one. Click on @{"Install" link "Win IGad"} or @{"Skip" link "Win SGad"} to make your choice. This process
is repeated for all icons in the directory.
You can instruct IconInstaller to complete the directory without further
interaction by clicking on the @{"All" link "Win AGad"} gadget. A requester will appear, asking
you to confirm this option.
You can also click on the @{"Quit" link "Win QGad"} gadget at any point, to abort the directory
installation.
The 'Settings' menu contains options to change the behaviour of directory
installation. The options can be changed by setting and clearing subitems
for the @{"Directory" link "SMenu Dir"} menuitem. The options available are 'Match Type',
'Create Icons' and 'Enter Directories'.
Match Type will accept for installation only those icons that are of the
same type as the source icon.
Create Icons will give you the option to create icons for files that don't
have icons.
Enter Directories means that the installation will proceed not only in this
directory, but all its subdirectories as well.
@endnode
@node "SMode" "USAGE"
@toc "Usage"
2.3. SCRIPT MODE
Using IconInstaller in script mode is actually the easiest way to use it.
You don't even have to open icons for installation, as they are selected
automatically by the script.
You start a script by double clicking on the script's icon.
If you are using the @{"NewIcons" link "NIInfo"} system, a requester may appear asking you
to select from some options relating to the imagery installation.
The IconInstaller window will be opened as usual. IconInstaller will start
to open source and destination icons according to the script, presenting you
the new image from the source icon, and the original image of the
destination icon, side by side, before the installation. You can click on
these images to see the alternate imagery, if there is any.
For each icon you can select if you want to install the new image to the
destination icon, or keep the original image. Click on @{"Install" link "Win IGad"} or @{"Skip" link "Win SGad"},
respectively, to make your choice. IconInstaller will then open the next
source and destination icons according to the script. This process is
repeated for each pair of icons, until the script is complete.
As in the @{"directory
mode" link "DMode"}, you can instruct IconInstaller to complete the
script without further interaction, by clicking on the @{"All" link "Win AGad"} gadget. A
requester will appear asking you to confirm that you really want to do this.
You can also click on the @{"Quit" link "Win QGad"} gadget at any point, to abort the script
and reset IconInstaller to @{"basic
usage" link "BMode"}.
Depending on the script, you may also be presented with messages and
requesters either to give you information, or prompt you to select from
some available options.
An IconInstaller script is a standard ASCII text file, that can be created
with any text editor, such as 'Ed' or 'Emacs'. For icon authors wanting to
distribute IconInstaller with their releases, or other users wishing to
automate the installation of a large number of icons, there is a section
about @{"writing your own scripts" link "SWrite"}, as well as a @{"reference section" link "SCom"} with all
commands and options available.
@endnode
@node "Config" "USAGE"
@toc "Usage"
2.4. CONFIGURATION
In its default configuration, IconInstaller will copy the imagery from one
icon to another, while retaining the other attributes of the destination
icon, such as tooltypes, default tool, position, and so on. If you have the
@{"NewIcons" link "NIInfo"} patch running, the default action is to copy the NewIcon image,
while keeping the standard image as it is.
The default configuration can be changed with @{"tooltypes" link "TTypes"} in the IconInstaller
icon, so that every time you start IconInstaller, your preferred
configuration is active. To change the default configuration for a
script, tooltypes in the script's icon should be set instead.
While using IconInstaller, the configuration can be changed from the
@{"Settings" link "SMenu"} menu.
The menu contains options for manipulating the @{"Image" link "SMenu Image"}, the @{"NewIcon imagery" link "SMenu NIcon"},
@{"Icon Type" link "SMenu IType"}, @{"Default Tool" link "SMenu DTool"}, @{"Tool Types" link "SMenu TTypes"}, @{"Position" link "SMenu Pos"} and @{"Stack" link "SMenu Stack"}.
All of these attribute settings contain at least two options, 'Keep Original'
and 'Copy From Source'. The former means that the attribute in the destination
icon is not changed, the latter means that the attribute is copied from the
source icon to the destination icon.
The 'Image' and NewIcon settings also contain options to convert imagery from
the standard to NewIcon format, and vice versa. The 'Icon Type' and 'Default
Tool' settings contain many options to set the attribute explicitely.
In addition to the attribute settings, the 'Settings' menu also includes
@{"directory options" link "SMenu Dir"} to affect the behaviour of directory installation.
Finally, there is an option to @{"quickly install icons" link "SMenu DDrop"} with dragging
and dropping.
@endnode
@node "SWrite" "USAGE"
@toc "Usage"
2.5. WRITING ICONINSTALLER SCRIPTS
An IconInstaller script is a standard ASCII text file, that can be
created with any half-decent text editor, such as the 'Ed' editor
supplied with AmigaDOS.
An icon has to be created for the script, as currently the only way
to start a script is to double click on the script icon on Workbench.
The script icon type must be 'Project', and the default tool must
be 'IconInstaller'. The script icon can be conveniently created with
IconInstaller itself, for example.
IconInstaller will identify a script by examining the first line.
The first line has to start with the keyword
@{"ICONINSTALLER" link "SCom II"}
so that IconInstaller will know that this file is meant as a script.
Optionally, a version number may be included after the ICONINSTALLER
keyword. This guarantees that the script will not be executed with
an older version of IconInstaller. If you are using script commands
that are not available in early versions of IconInstaller, it could
be worthwhile to specify the version number. Version 3.0 can be
assumed as the lowest possible version number.
Empty lines and lines starting with a semi-colon (@{";" link "SCom Rem"}) are ignored
by IconInstaller. This way, comments and extra spaces can be included
for better readability.
The command to install the imagery from one icon to another takes
always the following form:
@{"FROM" link "SCom From"} <Source Icon> @{"TO" link "SCom To"} <Destination Icon> [OPTIONS]
If an icon name contains blank spaces, the name must be included in
quotes. The trailing .info extension for an icon file name may be included,
but it is not necessary.
For example, the command
FROM Icon_1 TO "Icon 2"
Will copy the imagery from Icon_1 to Icon 2.
There are seven options available for icon installation commands.
The options can be used alone or in any combination. Not all combinations
are very useful, though. The options are
@{" ICONTYPE " link "SCom IType"} Specify the type for the destination icon
@{" QUIET " link "SCom Quiet"} Suppress any 'Please insert volume...' requesters
@{" FORCE " link "SCom Force"} Create the destination icon if it doesn't exist
@{" MATCHTYPE " link "SCom Match"} Skip the destination icon if its type doesn't match the source
@{" DIRECTORY " link "SCom Dir"} Install to all icons in a directory (drawer)
@{" RAMSCRIPT " link "SCom Ram"} Offer to append a Ram Disk icon script to S:User-Startup
@{" CHECKSYS " link "SCom CSys"} Look around the SYS: disk for the destination icon
In addition to the icon installation command, there are three more
commands available.
The level of automation can be specified with the SCRIPTMODE command.
The format for this command is
@{"SCRIPTMODE" link "SCom Mode"} <AUTOMATIC|SKIP|MANUAL>
SKIP is the default mode, and provides good manual control. The AUTOMATIC
mode will install everything without any confirmation. It is NOT recommended
to set the AUTOMATIC mode for scripts that are distributed with icon
collections to the general public. The MANUAL mode gives the user the best
manual control, as even skipping of icons that are not found must be
confirmed.
It is also possible to display messages to the user. This is done with the
MESSAGE command. The format for this command is
@{"MESSAGE" link "SCom Msg"} "<Show this text>"
A requester will be displayed, containing the text and a single 'OK'
gadget. If the text to be displayed contains any blank spaces, include it
in quotes. The special character combination ('\n') can be used to split
the text in the requester on several lines.
Some icons require a custom Workbench palette to make sure that the icons
appear correctly. This is because normal Amiga icons don't contain any
colour data, and depend on the Workbench palette for their looks. It is
possible to install a palette from within a script with the INSTALLPALETTE
command. The format for this command is
@{"INSTALLPALETTE" link "SCom IPal"} "Palette file"
The argument is the name of the file that contains the palette to be
installed. A requester will be displayed, offering the user the option
to install the palette.
Two additional options, @{"IFNEWICONS" link "SCom IfNI"} and @{"IFNOTNEWICONS" link "SCom IfNotNI"}, can be used in
combination with the SCRIPTMODE, MESSAGE and INSTALLPALETTE commands.
If the IFNEWICONS option is used, the command will be executed only if
the NewIcons patch is installed on the user's system. The IFNOTNEWICONS
option has the opposite effect, causing the command to be executed only
if the NewIcons patch is NOT present.
If you are reading this documentation from the original IconInstaller
archive, there is a fully commented example script called 'Install_Icons'
included. Click @{"here" link "Install_Icons/main"} to take a look at the example script.
If you intend to distribute a script with an icon collection for the
general public, it is recommended that the @{"NOSETTINGS" link "TType NoSet"} and
@{"ASKNEWICONS" link "TType AskNI"} tooltypes are set in the script's icon, but not any
other tooltype. This will guarantee that only the imagery will be installed,
and that the user will not be able to modify the settings in the middle of a
script. Read the @{"copyright" link "Copy"} section for more distribution information.
@endnode
@node "Ref" "REFERENCE"
3. REFERENCE
This chapter contains reference information for the IconInstaller window,
the menus, the tooltypes and the script commands. For each section, a
brief overview will first be presented, with more detailed description
for every item available by selecting from the overview list.
@{" 3.1. WINDOW " link "Win"} The elements in the IconInstaller window
@{" 3.2. MENUS " link "Menu"} The menuitems and subitems in the menus
@{" 3.3. TOOLTYPES " link "TTypes"} All available tooltypes and their options
@{" 3.4. SCRIPT COMMANDS " link "SCom"} All keywords and options available in scripts
@endnode
@node "Win" "REFERENCE"
@toc "Ref"
3.1. WINDOW
This is a brief list of all elements in the IconInstaller main window.
This includes all gadgets and areas for icon dragging and dropping.
For a more complete description for each element, click on any item on
the list below.
@{" SOURCE ICON BOX " link "Win SBox"} Displays the new icon image
@{" DESTINATION ICON BOX " link "Win DBox"} Displays the original icon image
@{" INSTALL GADGET " link "Win IGad"} Install the imagery to the destination icon
@{" DIR GADGET " link "Win DGad"} Install to all icons in a directory
@{" ALL GADGET " link "Win AGad"} Install rest of script/directory automatically
@{" SKIP GADGET " link "Win SGad"} Skip the destination icon in script/directory mode
(.txt)